package com.winsdom.service.customer;

import com.winsdom.entity.customer.CustomerPersonalBasicInfoRequest;

/**
 * 个人客户基本信息查询服务接口
 * <p>
 * 该接口负责提供个人客户基本信息的查询功能，包括：
 * 1. 客户主表信息（姓名、手机号、邮箱等）
 * 2. 个人扩展信息（证件类型、证件号码等）
 * 3. 证件图片路径信息
 * 4. 关联的联系人信息及其对应的楼盘分类信息
 * <p>
 * 查询结果以结构化的{@link CustomerPersonalBasicInfoRequest}对象形式返回，
 * 所有关联数据通过对象嵌套关系呈现，避免使用Map导致的类型不明确问题。
 */
public interface CustomerPersonalBasicInfoService {

    /**
     * 根据客户ID查询个人客户的完整基本信息
     * <p>
     * 业务流程：
     * 1. 校验客户类型是否为个人（类型码3），若不是则抛出异常
     * 2. 查询客户主表信息，包括基本联系方式
     * 3. 查询个人扩展信息，如证件类型和证件号码
     * 4. 查询证件图片路径信息（如有）
     * 5. 查询关联的联系人信息及其对应的楼盘分类信息
     * 6. 将所有信息整合到{@link CustomerPersonalBasicInfoRequest}对象中返回
     * <p>
     * 返回对象结构说明：
     * <pre>
     * CustomerPersonalBasicInfoRequest {
     *   Long customerId;                // 客户ID
     *   Integer customerType;           // 客户类型（固定为3，表示个人）
     *   String customerName;            // 客户姓名
     *   String mobilePhone;             // 手机号码
     *   String email;                   // 电子邮箱
     *   String idType;                  // 证件类型
     *   String idNumber;                // 证件号码
     *   String idImagePath;             // 证件图片路径
     *   List<ContactInfo> contactInfos; // 联系人列表
     * }
     *
     * ContactInfo {
     *   Long contactId;                 // 联系人ID
     *   String contactName;             // 联系人姓名
     *   String contactMobile;           // 联系人电话
     *   String contactEmail;            // 联系人邮箱
     *   List<String> receiveProperties; // 关联的楼盘分类名称列表（去重）
     * }
     * </pre>
     *
     * @param customerId 个人客户ID（主键）
     * @return 封装了个人客户完整基本信息的实体对象
     * @throws IllegalArgumentException 当客户ID不存在或客户类型不是个人时抛出
     */
    CustomerPersonalBasicInfoRequest getCustomerPersonalBasicInfo(Long customerId);
}